home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / gawk / gawk215b.zoo / gawk.man < prev    next >
Text File  |  1993-06-28  |  43KB  |  1,093 lines
  1. GAWK(1)                 ST Programmer Manual                   GAWK(1)
  2.  
  3. NAME
  4.      gawk - pattern scanning and processing language
  5.  
  6. SYNOPSIS
  7.      gawk [ POSIX or GNU style options ] -f program-file [ -- ]
  8.      file ...
  9.      gawk [ POSIX or GNU style options ] [ -- ] program-text file
  10.      ...
  11.  
  12. DESCRIPTION
  13.      Gawk is the GNU Project's implementation of the AWK program-
  14.      ming language.  It conforms to the definition of the
  15.      language in the POSIX 1003.2 Command Language And Utilities
  16.      Standard.  This version in turn is based on the description
  17.      in The AWK Programming Language, by Aho, Kernighan, and
  18.      Weinberger, with the additional features defined in the Sys-
  19.      tem V Release 4 version of UNIX awk.  Gawk also provides
  20.      some GNU-specific extensions.
  21.  
  22.      The command line consists of options to gawk itself, the AWK
  23.      program text (if not supplied via the -f or --file options),
  24.      and values to be made available in the ARGC and ARGV pre-
  25.      defined AWK variables.
  26.  
  27. OPTIONS
  28.      Gawk options may be either the traditional POSIX one letter
  29.      options, or the GNU style long options.  POSIX style options
  30.      start with a single ``-'', while GNU long options start with
  31.      ``--''.  GNU style long options are provided for both GNU-
  32.      specific features and for POSIX mandated features.  Other
  33.      implementations of the AWK language are likely to only
  34.      accept the traditional one letter options.
  35.  
  36.      Following the POSIX standard, gawk-specific options are sup-
  37.      plied via arguments to the -W option.  Multiple -W options
  38.      may be supplied, or multiple arguments may be supplied
  39.      together if they are separated by commas, or enclosed in
  40.      quotes and separated by white space.  Case is ignored in
  41.      arguments to the -W option.  Each -W option has a
  42.      corresponding GNU style long option, as detailed below.
  43.  
  44.      Gawk accepts the following options.
  45.  
  46.      -F fs
  47.      --field-separator=fs
  48.           Use fs for the input field separator (the value of the
  49.           FS predefined variable).
  50.  
  51.      -v var=val
  52.      --assign=var=val
  53.           Assign the value val, to the variable var, before exe-
  54.           cution of the program begins.  Such variable values are
  55.           available to the BEGIN block of an AWK program.
  56.  
  57.      -f program-file
  58.      --file=program-file
  59.           Read the AWK program source from the file program-file,
  60.           instead of from the first command line argument.  Mul-
  61.           tiple -f (or --file) options may be used.
  62.  
  63.      -W compat
  64.      --compat    Run in compatibility mode.  In compatibility
  65.                  mode, gawk behaves identically to UNIX awk; none
  66.                  of the GNU-specific extensions are recognized.
  67.                  See GNU EXTENSIONS, below, for more information.
  68.  
  69.      -W copyleft
  70.      -W copyright
  71.      --copyleft
  72.      --copyright Print the short version of the GNU copyright
  73.                  information message on the error output.
  74.  
  75.      -W help
  76.      -W usage
  77.      --help
  78.      --usage     Print a relatively short summary of the avail-
  79.                  able options on the error output.
  80.  
  81.      -W lint
  82.      --lint      Provide warnings about constructs that are dubi-
  83.                  ous or non-portable to other AWK implementa-
  84.                  tions.
  85.      -W posix
  86.      --posix     This turns on compatibility mode, with the fol-
  87.                  lowing additional restrictions:
  88.  
  89.                  o✓+ \x escape sequences are not recognized.
  90.  
  91.                  o✓+ The synonym func for the keyword function is
  92.                    not recognized.
  93.  
  94.                  o✓+ The operators ** and **= cannot be used in
  95.                    place of ^ and ^=.
  96.  
  97.      -W source=program-text
  98.      --source=program-text
  99.                  Use program-text as AWK program source code.
  100.                  This option allows the easy intermixing of
  101.                  library functions (used via the -f and --file
  102.                  options) with source code entered on the command
  103.                  line.  It is intended primarily for medium to
  104.                  large size AWK programs used in shell scripts.
  105.                  The -W source= form of this option uses the rest
  106.                  of the command line argument for program-text;
  107.                  no other options to -W will be recognized in the
  108.                  same argument.
  109.  
  110.      -W version
  111.      --version   Print version information for this particular
  112.                  copy of gawk on the error output.  This is use-
  113.                  ful mainly for knowing if the current copy of
  114.                  gawk on your system is up to date with respect
  115.                  to whatever the Free Software Foundation is dis-
  116.                  tributing.
  117.  
  118.      --          Signal the end of options. This is useful to
  119.                  allow further arguments to the AWK program
  120.                  itself to start with a ``-''.  This is mainly
  121.                  for consistency with the argument parsing con-
  122.                  vention used by most other POSIX programs.
  123.  
  124.      Any other options are flagged as illegal, but are otherwise
  125.      ignored.
  126.  
  127. AWK PROGRAM EXECUTION
  128.      An AWK program consists of a sequence of pattern-action
  129.      statements and optional function definitions.
  130.  
  131.           pattern   { action statements }
  132.           function name(parameter list) { statements }
  133.  
  134.      Gawk first reads the program source from the program-file(s)
  135.      if specified, or from the first non-option argument on the
  136.      command line.  The -f option may be used multiple times on
  137.      the command line.  Gawk will read the program text as if all
  138.      the program-files had been concatenated together.  This is
  139.      useful for building libraries of AWK functions, without hav-
  140.      ing to include them in each new AWK program that uses them.
  141.      To use a library function in a file from a program typed in
  142.      on the command line, specify /dev/tty as one of the
  143.      program-files, type your program, and end it with a ^D
  144.      (control-d).
  145.  
  146.      The environment variable AWKPATH specifies a search path to
  147.      use when finding source files named with the -f option.  If
  148.      this variable does not exist, the default path is
  149.      ".,c:/lib/awk,c:/gnu/lib/awk".  If a file name given
  150.      to the -f option contains a ``/'' character, no path search
  151.      is performed.
  152.  
  153.      Gawk executes AWK programs in the following order.  First,
  154.      gawk compiles the program into an internal form.  Next, all
  155.      variable assignments specified via the -v option are per-
  156.      formed.  Then, gawk executes the code in the BEGIN block(s)
  157.      (if any), and then proceeds to read each file named in the
  158.      ARGV array.  If there are no files named on the command
  159.      line, gawk reads the standard input.
  160.  
  161.      If a filename on the command line has the form var=val it is
  162.      treated as a variable assignment. The variable var will be
  163.      assigned the value val.  (This happens after any BEGIN
  164.      block(s) have been run.) Command line variable assignment is
  165.      most useful for dynamically assigning values to the vari-
  166.      ables AWK uses to control how input is broken into fields
  167.      and records. It is also useful for controlling state if mul-
  168.      tiple passes are needed over a single data file.
  169.  
  170.      If the value of a particular element of ARGV is empty (""),
  171.      gawk skips over it.
  172.  
  173.      For each line in the input, gawk tests to see if it matches
  174.      any pattern in the AWK program.  For each pattern that the
  175.      line matches, the associated action is executed.  The pat-
  176.      terns are tested in the order they occur in the program.
  177.  
  178.      Finally, after all the input is exhausted, gawk executes the
  179.      code in the END block(s) (if any).
  180.  
  181. VARIABLES AND FIELDS
  182.      AWK variables are dynamic; they come into existence when
  183.      they are first used. Their values are either floating-point
  184.      numbers or strings, or both, depending upon how they are
  185.      used. AWK also has one dimension arrays; multiply
  186.      dimensioned arrays may be simulated.  Several pre-defined
  187.      variables are set as a program runs; these will be described
  188.      as needed and summarized below.
  189.  
  190.      Fields
  191.  
  192.      As each input line is read, gawk splits the